在API的設計中,資料格式是溝通的語言,即使端點設計合理,如果資料格式混亂,不僅會增加開發者理解的困難,也可能造成程式錯誤或系統不穩定,因此,保持資料的一致性與標準化,是API設計的重要基礎。
常用格式
現代API最常見的資料交換格式是JSON,結構簡單、可讀性高,也方便程式解析。相比之下XML雖然仍被部分系統使用,但JSON更輕量,也更符合網頁與行動應用的需求。
欄位命名規範
命名方式應保持一致,例如全部使用camelCase(如userName
)或snake_case(如user_name
),避免在同一個API裡混用,這樣能讓開發者更快理解資料結構。
資料型別統一
同一種資料要保持一致的型別,例如布林值固定使用true
與false
,數字只用數字,不要混雜單位。若需要單位,應該額外提供欄位而不是直接寫在數字裡。
格式標準化
日期與時間建議採用ISO 8601標準格式,例如 2025-09-15T10:00:00Z
,這樣不同系統之間不會因格式差異造成混亂,小數或金額也要統一,避免有的回傳兩位小數,有的回傳四位小數。
欄位說明清楚
每個欄位都應該在文件中標註清楚,包括它的用途、型別、是否必填,並且提供範例,能降低使用API時的試錯成本。
回應結構一致性
不管成功還是失敗,API回應結構應保持一致。常見做法是統一包含 status
、message
以及 data
區塊,避免開發者需要為不同情況寫額外的解析邏輯。